## -*- mode: html; coding: utf-8; -*-

## This file is part of CDS Invenio.
## Copyright (C) 2002, 2003, 2004, 2005, 2006, 2007, 2008 CERN.
##
## CDS Invenio is free software; you can redistribute it and/or
## modify it under the terms of the GNU General Public License as
## published by the Free Software Foundation; either version 2 of the
## License, or (at your option) any later version.
##
## CDS Invenio is distributed in the hope that it will be useful, but
## WITHOUT ANY WARRANTY; without even the implied warranty of
## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
## General Public License for more details.
##
## You should have received a copy of the GNU General Public License
## along with CDS Invenio; if not, write to the Free Software Foundation, Inc.,
## 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA.

<!-- WebDoc-Page-Title: WebJournal Editor Guide -->
<!-- WebDoc-Page-Navtrail: <a class="navtrail" href="<CFG_SITE_URL>/help/admin<lang:link/>">_(Admin Area)_</a> -->
<!-- WebDoc-Page-Revision: $Id$ -->
<h2>Contents</h2>

<ul style="list-style-type:None">
<li><strong>1. <a href="#introduction">Introduction</a></strong>
    <ul style="list-style-type:None">
    <li>1.1&nbsp;&nbsp;<a href="#introductionConcepts">Concepts</a></li>
    </ul>
</li>
<li><strong>2. <a href="#addArticle">Submit an Article</a></strong>
    <ul style="list-style-type:None">
      <li><strong>2.1 <a href="#webEditor">Using the web HTML editor</a></strong></li>
      <li><strong>2.1 <a href="#offlineVsOnline">Offline VS online</a></strong></li>
    </ul>
</li>
<li><strong>3. <a href="#editArticle">Edit an Article</a></strong></li>
<li><strong>4. <a href="#editArticle">Feature a Record</a></strong></li>
<li><strong>5. <a href="#previewIssue">Preview an Issue</a></strong></li>
<li><strong>6. <a href="#releaseIssue">Release an Issue</a></strong>
    <ul style="list-style-type:None">
      <li><strong>6.1 <a href="#issueUpdates">Issue Updates</a></strong></li>
    </ul>
</li>
<li><strong>7. <a href="#sendAlert">Send an Alert</a></strong></li></li>
<li><strong>8. <a href="#cache">Regenerate Your Journal</a></strong></li>
<li><strong>9. <a href="#adminTasks">Other Administrative tasks</a></strong></li>
</ul>

<h2><a name="introduction">1. Introduction</a></h2>

<p>WebJournal is a module of CDS Invenio that assists you in publishing
an online journal.  This guide should help you get familiar with the
tools offered by WebJournal.
</p>

<h3><a name="introductionConcepts">1.1 Concepts</a></h3>

<p>
An <strong>online journal</strong> (managed by WebJournal) is similar
to the widespread "<em>blogs</em>" systems, with the major difference
that articles of an online journal are grouped by
"<strong>issues</strong>": new blog articles usually push old articles
away one after the other, while an online journal wipes out all the
previous articles once a new issue is <strong>released</strong>.
</p>

<p>
As an editor of an online journal, you will have the task to release
an issue once all the articles of this issue have been submitted into
the system. The new release becomes the current one and is accessible
online, while the old issue is archived.
</p>

<p>
Once an issue has been released, you have the possibility to send an
email <b>alert</b> to notify your subscribers about the availability of
a new issue. This alert can contain custom text, or embed your journal
homepage (in the manner of a <b>newsletter</b>).
</p>


<b>More about the issues:</b><br/>

<p>Issues of a journal are
numbered: <code>10/2009</code>, <code>11/2009</code>, <code>12/2009</code>,
etc. Every new release increments the previous number, and each year
the issue number is
reset: <code>12/2009</code>, <code>1/2010</code>, <code>2/2010</code>.</p>

<p>The format of the issue numbers is important ("number/year") as it
is used in WebJournal URLs (in the reverse form). You can therefore
not really go for another format, though you have the possibility to
display it in a different way on the journal page, thanks to
customizable templates.</p>

<p>The number of issues per year should be defined in advance, though
it is possible to have a variable number of issues (the system
proposes the next issue number, but you can choose to override it with
your own issue number). It is even possible to skip issue numbers,
though it is not
recommended: <code>1/2010</code>, <code>3/2010</code>, <code>5/2010</code>,
etc.</p>

<p>Issues can be <b><a name="groupedIssue">grouped</a></b> together to
make a "<b>publication</b>": this is typically used when you want to
publish an issue every two weeks, with a small update every second two
weeks: Issue <code>10/2009</code> has brand new articles, while the
next issue <code>11/2009</code> should feature the same articles, plus
a few new updates. <br/>Issues must be grouped before they are
released: you cannot decide to group the next issue to be released
with the latest issue.<br/> When grouping issues, you first release
the group as a whole, and then "update" the group when you thing they
are ready. For example you release the group <code>[10/2009,
11/2009]</code> the first week: <code>10/2009</code> becomes the
current issue. The next week, you <b>update</b>
issue <code>10/2009</code>: the publication <code>10-11/2009</code>
becomes the current issue.</p>


<b>More about the articles:</b><br/>

<p>The articles submitted to WebJournal are considered as regular
bibliographic records: the same treatment is applied to them, and the
bibliographic tools found in CDS Invenio can be used to manipulate
them.<p>


<p>As a consequence WebJournal articles also appear on the regular
search system of <CFG_SITE_NAME>. In order for articles of unreleased
issues not to appear on the regular search interface, the articles are
flagged as <b>offline</b> until the issue they belong to is released
(the articles are then flagged <b>online</b>).</p>


<p>Articles are submitted to specific categories of the journal (if
multiple categories are defined for your journal), and are assigned a
unique identifier: both attributes are visible in the URLs when
selecting an article. It is then easy to build links to an
article. The article identifier also corresponds to the identifier of
the entry in <CFG_SITE_NAME>.</p>

<h2><a name="addArticle">2. Submit an Article</a></h2>

<p>
To submit an article, go to
the <a href="<CFG_SITE_URL>/submit">regular submission page</a>, and
choose the category corresponding to your journal. <br/> (This can
vary depending on how the administrator configured the system).
</p>

<p>It is at submission time that you have to decide what issue(s) this
article is to be part of (this can be modified later by editing the
article). If you use "grouped issues", you have to specify that the
article belong to each individual issue of the group.</p>

<p>Note that a small delay exists between the time an article is
submitted and the time it appears online.</p>

<h3><a name="webEditor">2.1 Using the web HTML editor</a></h3>

<p>Depending on how the administrator configured the system, you might
be given the possibility to write your articles online as if you were
editing them from a desktop text editor. If you have already used such
a tool, you should feel at home with the provided editor.</p>

<p>This editor translates your articles into HTML markup, ready for
displaying in a web browser. You therefore do not need to know how to
write HTML code, but you should be aware of a few consequences due to
online publishing. Here is a list of best practices when using the
online HTML editor:
<ul>
<li>You can copy-paste text from other editors. Note that the
formatting (font, color, size) might not be kept correctly in some
cases. If you copy-paste text from Microsoft Word, please use the
dedicated "Word-text cleaner" button of the toolbar.</li>
<li>If you want to paste styled text but you do not want to keep its
style, use the dedicated "Text cleaner" button of the toolbar.</li>
<li>Pasting text from your own machine that contains images (or any
multimedia content) will not paste the images, but just the text. To
have your images, you must first upload them to the server using the
"Image" button of the toolbar, and click on the "Upload" tab.</li>
<li>Do not upload big images: they might take a long time to load in
your readers' browsers. WebJournal will usually try to scale down the
images, but you would achieve better effect by first reducing them
using a dedicated image processing application.</li>
<li>If you want to display images that already exist online, you do
not need to download them and re-upload them: you can simply link them
("Image" button of the toolbar, link to the image).</li>
<li>Try not to use custom styles (colors, font, size): you should
restrict to a layout and styles that have a semantic meaning for your
article (paragraphs, <strike>stroked text</strike>, <em>italics</em>,
header, etc.) and let WebJournal applies the corresponding styles:
that will ensure a consistent look of all the articles over time, and
will make possible future re-styling of your journal, even of your
past issues.</li>
<li>You can view the source of the produced HTML, if you need to apply
specific modifications that are unsupported by the online editor (for
eg. linking to a video).</li>
</ul>
</p>

<h3><a name="offlineVsOnline">2.2 Offline VS Online</a></h3>
<p>Depending on how the system was configured by the administrator,
you might be given the choice to have your article offline or online
when adding or editing it:</p>

<dl>

<dt>Offline</dt>
<dd>The article is not visible on the regular search interface
of <CFG_SITE_NAME> until the issue has been released</dd>

<dt>Online</dt>
<dd>The article is immediately visible on the regular search interface
of <CFG_SITE_NAME>. You should use this option if you want to add an
article to an already released issue (otherwise the article will never
be visible on the regular search interface).</dd>
</dl>


<h2><a name="editArticle">3. Edit an Article</a></h2>

<p>
You can edit articles in same way as you add articles: you just have
to go to the <a href="<CFG_SITE_URL>/submit">regular submission
page</a> and provide the article number you want to modify.  If you
are logged in as editor of the journal, you should also see a direct
link to edit the article from the main article page of your
journal.<br/>  (This can vary depending on how the administrator
configured the system).
</p>

<h2><a name="editArticle">4. Feature a Record</a></h2>

<p> Depending on your journal configuration, you might be given the
possibility to feature on your main journal page records (photos,
videos, etc) found on <CFG_SITE_NAME>.

<p>
To feature a record, go to you
journal <a href="<CFG_SITE_URL>/admin/webjournal/webjournaladmin.py">administration
page</a>, and choose "Feature a record". You must then provide the
identifier of the record you want to feature, as well as the URL of
the image you want to associate to the record. On the very same page
you can remove featured records.
</p>

<p>Note that featured records are independent of releases: you can
update them whenever you want.</p>

<h2><a name="previewIssue">5. Preview an Issue</a></h2>

<p>
To preview an issue, go to your
journal <a href="<CFG_SITE_URL>/admin/webjournal/webjournaladmin.py">administration
page</a>, and select the "edit" link of the category you want to
preview.
</p>
<p>
You can also preview any issue of your journal by specifying the
correct issue number in your journal URL. In that case, make sure you
are logged into <a href="<CFG_SITE_URL>"><CFG_SITE_NAME></a>,
otherwise you will not be able to access the unreleased issue.
</p>


<h2><a name="releaseIssue">6. Release an Issue</a></h2>

<p>To release an issue, go to your
journal <a href="<CFG_SITE_URL>/admin/webjournal/webjournaladmin.py">administration
page</a>, and select "Release now". You should then be given the
choice of the issue number to release. By default the next issue
number is selected, but you can decide to:
<ul>
<li>Add a higher issue number to create a <a href="#groupedIssue">grouped
issue</a> ("publication")</li>
<li>Add a higher issue number and deselect the suggested one to skip
the release of the suggested issue number.</li>
<li>Add a custom issue number (Eg. the system suggest you issue
number <code>52/2008</code>, but you want to jump
to <code>01/2009</code>)</li>
</ul>
You can group as many issue as you want. Only the selected issue
number(s) will be published. Click on the "Publish" button once done.
</p>


<h3><a name="issueUpdates">6.1 Issue Updates</a></h3>


<p>We call <b>issue update</b> the action of releasing an individual
issue of a grouped issue ("publication"). Eg. you grouped
issues <code>[15/2009, 16/2009]</code>: releasing
issue <code>16/2009</code> is an update to the publication <code>15-16/2009</code></p>

<p>If you have previously grouped some issues, you first have to
publish the pending one before releasing a completely new
issue. Eg. you want to release issue <code>17/2009</code> but you had
previously grouped the issues <code>[15/2009, 16/2009]</code>, without
releasing issue <code>16/2009</code>: you first have to release the
pending update <code>16/2009</code> before you can
release <code>17/2009</code>.</p>

<p>If you just want to add an article to an already released issue
without using grouped issues, simply submit your article for this
issue, and <a href="#cache">update the cache</a>.</p>


<h2><a name="sendAlert">7. Send an Alert</a></h2>
<p>
To send an alert about a new issue, go to your
journal <a href="<CFG_SITE_URL>/admin/webjournal/webjournaladmin.py">administration
page</a>, and click on the "send alert" link for the issue you
want to send the alert.<br/>

Update the recipients address and the text of the alert if needed.<br/>

If you keep the box "Send journal front-page" checked, your subscribers will
receive the front page of your new release by email. If you uncheck
this box (or if your subscribers have configured their email clients
to not display HTML emails) the textual version of the alert will be
shown instead.
</p>
<p>Note that you can only send an alert for an issue that has been
already released, and that you will be warned if you try to send an
alert that has already been sent for a past issue.</p>

<h2><a name="cache">8. Regenerate Your Journal</a></h2>
<p>
In order to optimize the display speed of the journal for your
readers, the WebJournal module creates static versions of your
journal. These static pages need to be recreated if you update the
journal after it has been released.
</p>

<p>To do so, go to your
journal <a href="<CFG_SITE_URL>/admin/webjournal/webjournaladmin.py">administration
page</a>, and click on the "regenerate" link of the issue you want to update.</p>

<h2><a name="adminTasks">9. Other Administrative tasks</a></h2>

<p>Administrative tasks such as adding or removing a journal, editing
its layout and settings have to be performed by an administrator-level
user.
</p>
<p>
Please refer to <a href="<CFG_SITE_URL>/help/admin/webjournal-admin-guide">WebJournal Admin Guide</a>.
</p>
